home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / clang / zcpp_jae.zip / CPP.MEM < prev    next >
Text File  |  1990-07-06  |  12KB  |  296 lines
  1.  
  2.  
  3.  
  4.  
  5.         1.0  C Pre-Processor
  6.  
  7.  
  8.  
  9.                                     *******
  10.                                     * cpp *
  11.                                     *******
  12.  
  13.  
  14.  
  15.         NAME:   cpp -- C Pre-Processor
  16.  
  17.         SYNOPSIS:
  18.  
  19.                 cpp [-options] [infile [outfile]]
  20.  
  21.         DESCRIPTION:
  22.  
  23.                 CPP reads a C source file, expands  macros  and  include
  24.                 files,  and writes an input file for the C compiler.  If
  25.                 no file arguments are given, CPP reads  from  stdin  and
  26.                 writes  to  stdout.   If  one file argument is given, it
  27.                 will define the input file,  while  two  file  arguments
  28.                 define  both  input and output files.  The file name "-"
  29.                 is a synonym for stdin or stdout as appropriate.
  30.  
  31.                 The following options are  supported.   Options  may  be
  32.                 given in either case.
  33.  
  34.                 -C              If set, source-file comments are written
  35.                                 to  the  output  file.   This allows the
  36.                                 output of CPP to be used as the input to
  37.                                 a  program,  such  as lint, that expects
  38.                                 commands embedded in specially-formatted
  39.                                 comments.
  40.  
  41.                 -Dname=value    Define the name  as  if  the  programmer
  42.                                 wrote
  43.  
  44.                                     #define name value
  45.  
  46.                                 at the start  of  the  first  file.   If
  47.                                 "=value"  is  not  given, a value of "1"
  48.                                 will be used.
  49.  
  50.                                 On non-unix systems, all alphabetic text
  51.                                 will be forced to upper-case.
  52.  
  53.                 -E              Always return "success" to the operating
  54.                                 system,  even  if  errors were detected.
  55.                                 Note that some fatal errors, such  as  a
  56.                                 missing  #include  file,  will terminate
  57.                                 CPP, returning "failure" even if the  -E
  58.                                 option is given.
  59.                                                                           Page 2
  60.         cpp     C Pre-Processor
  61.  
  62.  
  63.                 -Idirectory     Add  this  directory  to  the  list   of
  64.                                 directories  searched for #include "..."
  65.                                 and #include <...> commands.  Note  that
  66.                                 there  is  no space between the "-I" and
  67.                                 the directory string.  More than one  -I
  68.                                 command   is   permitted.   On  non-Unix
  69.                                 systems   "directory"   is   forced   to
  70.                                 upper-case.
  71.  
  72.                 -N              CPP  normally  predefines  some  symbols
  73.                                 defining   the   target   computer   and
  74.                                 operating system.  If -N  is  specified,
  75.                                 no symbols will be predefined.  If -N -N
  76.                                 is  specified,  the   "always   present"
  77.                                 symbols,    __LINE__,    __FILE__,   and
  78.                                 __DATE__ are not defined.
  79.  
  80.                 -Stext          CPP normally assumes that  the  size  of
  81.                                 the  target  computer's  basic  variable
  82.                                 types is the same as the size  of  these
  83.                                 types  of  the host computer.  (This can
  84.                                 be  overridden  when  CPP  is  compiled,
  85.                                 however.)  The  -S option allows dynamic
  86.                                 respecification of these values.  "text"
  87.                                 is  a  string  of  numbers, separated by
  88.                                 commas, that  specifies  correct  sizes.
  89.                                 The sizes must be specified in the exact
  90.                                 order:
  91.  
  92.                                     char short int long float double
  93.  
  94.                                 If you specify the option as  "-S*text",
  95.                                 pointers   to   these   types   will  be
  96.                                 specified.   -S*  takes  one  additional
  97.                                 argument  for  pointer to function (e.g.
  98.                                 int (*)())
  99.  
  100.                                 For   example,    to    specify    sizes
  101.                                 appropriate  for  a  PDP-11,  you  would
  102.                                 write:
  103.  
  104.                                        c s i l f d func
  105.                                      -S1,2,2,2,4,8,
  106.                                     -S*2,2,2,2,2,2,2
  107.  
  108.                                 Note that all values must be specified.
  109.  
  110.                 -Uname          Undefine the name as if
  111.  
  112.                                     #undef name
  113.  
  114.                                 were given.  On non-Unix systems, "name"
  115.                                 will be forced to upper-case.
  116.                                                                           Page 3
  117.         cpp     C Pre-Processor
  118.  
  119.  
  120.                 -Xnumber        Enable debugging code.  If no  value  is
  121.                                 given,  a value of 1 will be used.  (For
  122.                                 maintenence of CPP only.)
  123.  
  124.  
  125.         PRE-DEFINED VARIABLES:
  126.  
  127.                 When CPP begins processing, the following variables will
  128.                 have been defined (unless the -N option is specified):
  129.  
  130.                 Target computer (as appropriate):
  131.  
  132.                     pdp11, vax, M68000 m68000 m68k
  133.  
  134.                 Target operating system (as appropriate):
  135.  
  136.                     rsx, rt11, vms, unix
  137.  
  138.                 Target compiler (as appropriate):
  139.  
  140.                     decus, vax11c
  141.  
  142.                 The implementor may add definitions to this  list.   The
  143.                 default  definitions  match  the  definition of the host
  144.                 computer, operating system, and C compiler.
  145.  
  146.                 The following are always available unless undefined  (or
  147.                 -N was specified twice):
  148.  
  149.                     __FILE__    The  input  (or  #include)  file   being
  150.                                 compiled (as a quoted string).
  151.  
  152.                     __LINE__    The line number being compiled.
  153.  
  154.              __DATE__    The date of compilation as "Mmm dd yy"
  155.  
  156.             __TIME__    The time of compilation as "hh:mm:ss"
  157.  
  158.             __STDC__    The constant 1.
  159.  
  160.                 Thus,
  161.                                     printf("Bug at line %s,", __LINE__);
  162.                                     printf(" source file %s", __FILE__);
  163.                                     printf(" compiled on %s", __DATE__);
  164.  
  165.  
  166.         DRAFT PROPOSED ANSI STANDARD CONSIDERATIONS:
  167.  
  168.                 When CPP is itself compiled, many features of the  Draft
  169.                 Proposed  Standard  that  are incompatible with existing
  170.                                                                           Page 4
  171.         cpp     C Pre-Processor
  172.  
  173.  
  174.                 preprocessors may be  disabled.   See  the  comments  in
  175.                 CPP's source for details.
  176.  
  177.                 Comments are removed from the input text.   The  comment
  178.                 is  replaced by a single space character.  The -C option
  179.                 preserves comments, writing them to the output file.
  180.  
  181.                 The '$' character is considered to be a letter.  This is
  182.                 a permitted extension.
  183.  
  184.                 The following new features of C are processed by CPP:
  185.  
  186.                     #elif expression (#else #if)
  187.                     '\xNNN' (Hexadecimal constant)
  188.                     '\a' (Ascii BELL)
  189.                     '\v' (Ascii Vertical Tab)
  190.                     #if defined NAME 1 if defined, 0 if not
  191.                     #if defined (NAME) 1 if defined, 0 if not
  192.                     #if sizeof (basic type)
  193.                     unary +
  194.                     123U, 123LU Unsigned ints and longs.
  195.                     12.3L Long double numbers
  196.                     token#token Token concatenation
  197.                     #include token Expands to filename
  198.                 #error tokens       Flags an error
  199.  
  200.                 The Draft Proposed Standard has  extended  C,  adding  a
  201.                 constant string concatenation operator, where
  202.  
  203.                     "foo" "bar"
  204.  
  205.                 is regarded as the single string "foobar".   (This  does
  206.                 not  affect  CPP's  processing but does permit a limited
  207.                 form of macro argument substitution into strings as will
  208.                 be discussed.)
  209.  
  210.         The Standard Committee plans to add token concatenation
  211.         to #define command lines as follows:
  212.         The sequence "Token1 ## Token2" is treated
  213.         as if the programmer wrote "Token1Token2".  This could
  214.         be used as follows:
  215.  
  216.             #line 123
  217.             #define ATLINE foo ## __LINE__
  218.  
  219.                 ATLINE would be defined as foo123.
  220.                                                                           Page 5
  221.         cpp     C Pre-Processor
  222.  
  223.                 If the tokens T1 and T2 are concatenated into  T3,  this
  224.                 implementation operates as follows:
  225.  
  226.                   1. Expand T1 if it is a macro.
  227.                   2. Expand T2 if it is a macro.
  228.                   3. Join the tokens, forming T3.
  229.                   4. Expand T3 if it is a macro.
  230.  
  231.             If a macro parameter is immediately proceeded by a #, string
  232.             quotes (") are placed around the substituted parameter and
  233.             a \ character is inserted before each " or \ character that
  234.             appears surrounding,or inside a string literal or character
  235.             constant in the argument.
  236.  
  237.             Example:
  238.             #define vprint(name, size) \
  239.               printf(#name "[" "size" "] = {\n")
  240.                       ... vprint(vector, VECSIZE);
  241.  
  242.                 expands (effectively) to
  243.  
  244.                       vprint("vector[123] = {\n");
  245.  
  246.                 Note that  this  will  be  useful  if  your  C  compiler
  247.                 supports  the  new  string concatenation operation noted
  248.                 above.
  249.  
  250.     EXTENSIONS
  251.  
  252.         An extended macro facility is provided which allows and
  253.         arbitrary unix process to act as a macro expander.  To
  254.         define a macro do one of the following:
  255.  
  256.         #pragma defmacro name <file> options
  257.         #pragma defmacro name "file" options
  258.  
  259.         This provides a mapping between macro names and the file
  260.         to be executed, which is on the include search path.
  261.         "options" is zero or more of the following: 
  262.  
  263.         recursive    - when present, the macro is recursively expanded
  264.         delim=?      - the default delimiter of ; is replaced with ?
  265.         other        - other options are passed as arguments to the
  266.                    macro expander
  267.  
  268.         When a "defmacro" style macro's name is found, the name
  269.         and everything until the delimiter (includling all
  270.         matching {} [] () <> "" '' and comments found along the
  271.         way) is piped into the macro procedure's standard-input.
  272.         The procedure's standard output is scanned by CPP for
  273.         further processing. The expansion replaces the macro
  274.         call.
  275.  
  276.         ERROR MESSAGES:
  277.  
  278.                 Many.  CPP prints warning or error messages if  you  try
  279.                 to     use     multiple-byte     character     constants
  280.                 (non-transportable) if you #undef a symbol that was  not
  281.                 defined,  or  if  your  program  has  potentially nested
  282.                 comments.
  283.  
  284.         AUTHORS:
  285.  
  286.         Martin Minow (Origional version)
  287.             LaMott Oren  (Macro extensions and ANSI compatability)
  288.  
  289.         BUGS:
  290.  
  291.                 The #if expression processor uses signed integers  only.
  292.                 I.e, #if 0xFFFFu < 0 may be TRUE.
  293.  
  294.             This program differs from tha ANSI specification as follows:
  295.           Trigraph sequences aren't implemented.
  296.